home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Languages / MacQForth 1.0 / documentation / Glossary < prev    next >
Text File  |  1995-03-24  |  18KB  |  269 lines
  1.  
  2. Glossary
  3. --------
  4.  
  5.  
  6. A glossary of QForth words.  The format is:
  7.  
  8.  
  9. <word>   ( <stack-before> -- <stack-after> )
  10.  
  11.   <description of the word>
  12.   
  13.  
  14. ===============================================================================
  15.  
  16. !            ( n addr -- )
  17.  
  18.   Store a 16-bit value (n) and the address given (addr).
  19.   
  20.   Ex:  variable foo  ( define foo )
  21.        3422 foo !    ( put the number 3422 into foo )
  22.        
  23.        
  24. "           ( -- )
  25.  
  26.   Delimiter to mark the end of a string, used with ." and lit".
  27.   
  28.   
  29. '           ( -- addr )
  30.  
  31.   Places the address of the next word on the stack.
  32.   
  33.   Ex:  : hi ." Hello" cr ;   ( define a simple word                 )
  34.        variable foo          ( make a variable                      )
  35.        ' hi  foo !           ( save the address of hi's code in foo )
  36.        foo @ execute         ( causes hi to be run                  )
  37.        
  38. (             ( -- )
  39.  
  40.   Begins a comment.
  41.  
  42.   
  43. )            ( -- )
  44.  
  45.   Ends a comment.  Everything between ( and ) is ignored.
  46.  
  47.   
  48. *            ( n m -- m*n )
  49.  
  50.   Multiply two 16-bit: nada  34 >r 56 . r> . ;  displays  56 34
  51.   
  52.   
  53. r@            ( -- n )
  54.  
  55.   Copy the top return stack value to the stack.  Does not remove it.
  56.   
  57.   Ex:  : nada 34 >r 56 . r@ . r> . ;  displays 56 34 34 
  58.   
  59.   
  60. read        ( -- )
  61.  
  62.   Compile the source file whose name follows.  No spaces allowed in the 
  63.   name.
  64.   
  65.   Ex:  read intro   ( compile the intro file )
  66.   
  67.   
  68. repeat        ( -- )
  69.  
  70.   Finish a WHILE loop.  Colon definition only.
  71.   
  72.   Ex:  begin key 13 <> while  ." nope" cr  repeat
  73.   
  74.   
  75. rot            ( a b c -- b c a )
  76.  
  77.   Rotate top three stack items.
  78.   
  79.   
  80. space        ( -- )
  81.  
  82.   Print a space.  Equivalent to  32 emit 
  83.   
  84.   
  85. spaces        ( n -- )
  86.  
  87.   Print n spaces.
  88.   
  89.   
  90. span        ( -- n )
  91.  
  92.   Return the number of characters read during the most recent 'expect'.
  93.   
  94.   
  95. string        ( -- )
  96.  
  97.   Compile a string into the dictionary, delimited by a ~.
  98.   
  99.   Ex:  create s string foobar~
  100.        s 3 + c@ emit  gives  b
  101.  
  102.  
  103. swap        ( a b -- b a )
  104.  
  105.   Switch the top two stack values.
  106.   
  107.   
  108. true        ( -- -1 )
  109.  
  110.   Leave a -1 on the stack.
  111.   
  112.   
  113. u.            ( n -- )
  114.  
  115.   Unsigned print of top of stack.
  116.   
  117.   Ex:   -1 .  gives  -1
  118.         -1 u. gives  65535
  119.         
  120.         
  121. u<            ( n m -- 0 or -1 )
  122.  
  123.   Unsigned less than comparison.
  124.   
  125.   
  126. until        ( f -- )
  127.  
  128.   Colon definition only.  The bottom part of a BEGIN UNTIL loop.  The 
  129.   loop exits when f is true.
  130.   
  131.   Ex:  : ex  begin key dup emit 13 = until ;
  132.        display characters until return pressed.
  133.        
  134.        
  135. variable      ( -- )
  136.  
  137.   Create a dictionary entry for a variable with the next word as the name.
  138.   
  139.   Ex:  variable sweet-pea
  140.        1 sweet-pea !
  141.        
  142.        
  143. while        ( f -- )
  144.  
  145.   Colon definition only.  In a BEGIN WHILE REPEAT loop WHILE executes the 
  146.   part between WHILE and REPEAT as long as f is true.
  147.   
  148.   Ex:  : ex  begin key dup 13 <> while emit repeat ;
  149.   
  150.   
  151. words        ( -- )
  152.  
  153.   Display a list of all the defined words in the order in which they were 
  154.   defined.
  155.   
  156.   
  157. xor            ( n m -- 0 or -1 )
  158.  
  159.   Logical XOR (exclusive-OR) of n and m.  Return -1 (true) if either n or 
  160.   m is non-zero but return 0 if both n and m true.  One or the other but 
  161.   not both.
  162.   
  163.   
  164. xreg        ( -- addr )
  165.  
  166.   Return the address of the xreg variable.  The value of xreg is loaded 
  167.   into the X register just before an EXECUTE.
  168.   
  169.   
  170. yreg        ( -- addr )
  171.  
  172.   Return the address of the yreg variable.  The value of yreg is loaded 
  173.   into the Y register just before an EXECUTE.
  174.   
  175.  
  176. ===============================================================================
  177.  
  178. The following words are available after the file 'extend.4th' has been 
  179. loaded.
  180.  
  181.  
  182.  
  183. depth        ( -- n )
  184.  
  185.   Depth of the QForth stack, excluding n.
  186.   
  187.   
  188. !pen        ( x y -- )
  189.  
  190.   Move the graphics pen to screen coordinates x , y
  191.   
  192.   
  193. -to            ( x y -- )
  194.  
  195.   Draw a line from the current graphics pen position to x , y
  196.   
  197.   
  198. plot        ( x y -- )
  199.  
  200.   Plot the point at screen coordinates x,y
  201.   
  202.   
  203. color        ( n -- )
  204.  
  205.   Set the drawing color.  0 = black      4 = cyan
  206.                           1 = red        5 = magenta
  207.                           2 = green      6 = yellow
  208.                           3 = blue       7 = white
  209.   
  210.   All other colors are black.
  211.   
  212.   
  213. @mouse        ( -- x y b )
  214.  
  215.   Return the current mouse position and button status (0 or -1).
  216.   
  217.   
  218. ?button        ( -- 0 or -1 )
  219.  
  220.   Return the status of the mouse button, 0 = up, -1 = down.
  221.   
  222.   
  223. ?mouse        ( -- x y )
  224.  
  225.   Return the current mouse position.
  226.   
  227.   
  228. mon            ( -- )
  229.  
  230.   Start the MacQForth system monitor.  Enter q to exit.
  231.   
  232.   
  233. seedRandom    ( -- )
  234.  
  235.   Seed the random numbers in $FF8E and $FF8F.
  236.   
  237.   
  238. random        ( n -- m )
  239.  
  240.   Return a random number between 0 and n-1 inclusive.
  241.   
  242.   
  243. rand        ( -- 0..255 )
  244.  
  245.   Return a random number between 0 and 255.
  246.   
  247.   
  248. rand16        ( -- n )
  249.  
  250.   Return a random number between 0 and 65535.
  251.   
  252.   
  253. set-start    ( addr -- )
  254.  
  255.   Set the image startup word to addr.  When a memory image saved after 
  256.   set-start is executed is loaded the word at addr is run automatically.
  257.   
  258.   Ex:  : go ..... ;   ' go  set-start
  259.   
  260.  
  261. de            ( addr -- )
  262.  
  263.   Produce a disassembled listing of the machine code for the word whose 
  264.   address is on the stack.  Do not use with non-colon definition words.
  265.  
  266.   
  267. R@          ( -- n )
  268.  
  269.